'\" t
.\"     Title: IPSEC_RANBITS
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 10/06/2010
.\"    Manual: [FIXME: manual]
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "IPSEC_RANBITS" "8" "10/06/2010" "[FIXME: source]" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ipsec_newhostkey \- generate a new raw RSA authentication key for a host
.SH "SYNOPSIS"
.HP \w'\fBipsec\fR\ 'u
\fBipsec\fR \fInewhostkey\fR [[\-\-configdira\fInssdbdir\fR] | [\-\-password\ \fIpassword\fR]] [[\-\-quiet] | [\-\-verbose]] [\-\-bits\ \fIbits\fR] [\-\-hostname\ \fIhostname\fR] \-\-output\ \fIfilename\fR
.SH "DESCRIPTION"
.PP
\fInewhostkey\fR
outputs (into
\fIfilename\fR, which can be \'\-\' for standard output) an RSA private key suitable for this host, in
\fI/etc/ipsec\&.secrets\fR
format (see
\fBipsec.secrets\fR(5)) using the
\fB\-\-quiet\fR
option per default\&.
.PP
The
\fB\-\-output\fR
option is mandatory\&. The specified
\fIfilename\fR
is created under umask
\fB077\fR
if nonexistent; if it already exists and is non\-empty, a warning message about that is sent to standard error, and the output is appended to the file\&.
.PP
The
\fB\-\-quiet\fR
option suppresses both the
\fIrsasigkey\fR
narrative and the existing\-file warning message\&.
.PP
When compiled with NSS support,
\fB\-\-configdir\fR
specifies the nss configuration directory where the certificate key, and modsec databases reside\&. There is no default value, though /etc/ipsec\&.d might be sensible choice\&.
.PP
When compiled with NSS support,
\fB\-\-password\fR
specifies a module authentication password that may be required if FIPS mode is enabled
.PP
The
\fB\-\-bits\fR
option specifies the number of bits in the key; the current default is 2192 and we do not recommend use of anything shorter unless unusual constraints demand it\&.
.PP
The
\fB\-\-hostname\fR
option is passed through to
\fIrsasigkey\fR
to tell it what host name to label the output with (via its
\fB\-\-hostname\fR
option)\&.
.PP
The output format is that of
\fIrsasigkey\fR, with bracketing added to complete the
\fIipsec\&.secrets\fR
format\&. In the usual case, where
\fIipsec\&.secrets\fR
contains only the host\(^as own private key, the output of
\fInewhostkey\fR
is sufficient as a complete
\fIipsec\&.secrets\fR
file\&.
.SH "FILES"
.PP
/dev/random, /dev/urandom
.SH "SEE ALSO"
.PP
\fBipsec_rsasigkey\fR(8),
\fBipsec.secrets\fR(5)
.SH "HISTORY"
.PP
Written for the Linux FreeS/WAN project <\m[blue]\fBhttp://www\&.freeswan\&.org\fR\m[]> by Henry Spencer\&.
.SH "BUGS"
.PP
As with
\fIrsasigkey\fR, the run time is difficult to predict, since depletion of the system\(^as randomness pool can cause arbitrarily long waits for random bits, and the prime\-number searches can also take unpre dictable (and potentially large) amounts of CPU time\&. See
\fBipsec_rsasigkey\fR(8)
for some typical performance numbers\&.
.PP
A higher\-level tool which could handle the clerical details of changing to a new key would be helpful\&.
.PP
The requirement for
\fB\-\-output\fR
is a blemish, but private keys are extremely sensitive information and unusual precautions seem justified\&.
